This is an R Markdown!
R markdown is great, and when I say great, I mean REALLY great.
When exporting your markdown you can…
(1) embed figures
(2) view tables
(3) export models
(4) archive your data pipeline
You can write code and execute functions in a similar way to normal R script files. However, there are a few distinct differences between R scripts and R markdown scripts. Some of these differences relate to how code is executed. Other differences can be seen in the added benefit of integrating scripts with outputs and other embedded properties.
The benefit of using markdown with colleagues is they can actually see the script, the figures, the path of model selection, even the assumptions of ANOVA (QQ plots, etc) that normally are hidden behind the curtain. In short, R markdown helps make your science repeatable, sharable, and data analysis coherent!
Here are some common commands and examples of what Markdown can do for you. I reccommend visiting the R Bookdown for a complete and exhaustive guide https://bookdown.org/yihui/rmarkdown/ or the R markdown cheat sheet
Markdown basics
Common Commands
Notice the script at the very top of your markdown (this is not standard, but is customized)
output:
html_document:
code_folding: hide
toc: yes
toc_depth: 4
toc_float: yes ***
Let’s go through this line by line…
html_document: an option you originally set when you open the markdown. This is how your file will be exported.
code_folding: hidewill allow you to show or hide all code (option at top of file)
toc: for table of contents on the left
toc_depth: how long you will have table of contents before folding over
toc_float: lets your contents move as you advance in your document.
Play around with these options, and see how they affect your code
The setup chunk
r setup: This is your set up code and is a useful way to get around the fact that knitr will look for your .Rmd file and all files in the this directory. By setting the root.dir you can force knitr to look for files in the directory you specify and the folders within.
In the setup chunk (the first code chunk) you can set ‘global’ options, such as message/warning exclusion, or hiding results or outputs.
knitr::opts_chunk$set(warning=FALSE, message=FALSE): This command here is requiring the package knitr in the code chunk (‘set’ for set up) and is saying to “make all warning and message FALSE” i.e., hide them from output.
include=FALSE: this command makes your code absent from final html. It is executed but the code is hidden.eval=FALSE: this command allows you to show the code in your script within R studio, but not evaluate (or run) the code. It is effectively silent in your analysis and output html.echo=FALSE: this will show the output but not the code chunk… notice the difference.results='hide': this will hide all results in a code chunk, or any returned results from your commands.
Figure formatting
fig.show=FALSE: this will hide the figures you generate. This may be useful for some of those assumptions of ANOVA– you want to see it, but do you want all of them in your final archived datafile? Maybe not.fig.width=5, fig.height=3: The (graphical device) size of R plots in inches. This records your output figure as a graphical device using knitr and will write this to files. There are other ways to edit figure size from this intial dimension (see below). You can also specify the two (width and height using)fig.dim, as in the previous examlefig.dim = c(5, 3)out.widthandout.height: These set the output of a figure in output document. This is best to scale the image realtive to document dimensions, such asout.width= "50%"would be 50% of page width.fig.align: gives you figure alignment as either: right, center, left.dev: graphical devices, typicallypng(html) orpdffor LaTex.fig.cap: caption your figurefig.show: options here control your figures. Setting to'asis'will show plots in the location they were generated (similar to R terminal–this is the default). If you set to'hide'then the figures are generated but not shown in your output file. Another option below is my favorite.fig.show='hold': this is a really cool option. This option holds you plots and doesn’t display until the end of the code chunk. You can use it to place multiple figures side-by-side as long as theout.widthis called. For example, two plots side-by-side atout.widh="50%"
Now let’s use some of these options to see how this code could be executed.
data<-read.csv("data/coral_data.csv")
par(mar = c(4, 4, 0.2, 0.1))
plot(data$biomass, pch=16, cex=1.2, col="mediumseagreen")
plot(data$chla, pch=16, cex=1.2, col="coral")
Example of side-by-side plots at 50% with a ‘fig hold’ option
But something to consider… R scripts in code chunks operate a bit differently than classic R scripts. If you want to run your plot commands line-by-line you may need to include calls, such as with() or par(new=T) to specify that you do NOT want a new plot device to be made, but instead to keep working on the device you have opened.
# use results="hide" here to suppress messages associate with "dev.off" and dev.print to save figure
MC.df<-data[(data$Species=="MC"),] ## Montipora capitata alone
PC.df<-data[(data$Species=="PC"),] ## Porites compress alone
par(mar = c(4, 4, 3, 0.1))
plot(density(MC.df$biomass), lwd=2, col="darksalmon", xlim=c(0,100), main="Biomass in two coral species", xlab=expression(paste("Biomass mg cm"^-2, sep="")))
lines(density(PC.df$biomass), lwd=2, col="darkslategray3", yaxt="n", ylab="", xaxt="n", xlab="")
legend("topright", legend=c(expression(italic("Montipora capitata")), expression(italic("Porites compressa"))), lwd=2, col=c("darksalmon", "darkslategray3"), bty="n")
Tissue biomass in two coral species.
dev.print(pdf, "figures/biomass in two species.pdf", encod="MacRoman", height=4, width=6) # export in directory
dev.off()Text formatting
It is useful to understand how to modify text and format headings. You can do this in a variety of ways.
line break: this is executed by two spaces at the end of previous line, and a returnheadings: use#for headings,#….####and so on. # is largest and #### smallest heading
Italics comes from two calls italics or italics; bold is done the same way bold and bold
Superscriptsuperscript2 orstrikethroughsstrikethroughcan also be useful text modifiers.add linksto urls like this R studio linkendash: –
emdash: —
ellipsis: …inline equation: \(A = \pi*r^{2}\) or \(y = a*x+ b\)(a line can inserted with
***)
***
And don’t forget about adding in figures to your markdown from files/images in your directory…
Pa’āni is beautiful (and sassy). Beware!
Note in the code above I used the html codes for centering the image and the caption. You must leave a line between the first html call <center>, the caption and image code, and the end html code line of </center>.
Code chunks
## love your data and it will love you back
getwd()## [1] "/Users/chriswall/Desktop/zenodo/Intro to Markdown"Code chunks are where your code is executed. If you do not set the working directory in setup each code chunk will revert to its original directory, or where your .Rmd file lives. Below: This is a code chunk, and this is how you enter your data into R markdown. Note the code chunks always start with a ```{r... and ends with a ...}
The code chunk below is an example of attaching the data (.csv), familiar to you R-heads. Since the data file is in the directory specified by knitr::opts_knit$set(root.dir =... above, you can reference the .csv easily.
################################################
# import data, observe structure
################################################
# data file is in the folder 'data', within main working directory
data<-read.csv("data/coral_data.csv")
names(data)## [1] "Time.point" "Period" "Site" "Species" "Status"
## [6] "Sample.ID" "Pair" "Depth.ft" "biomass" "chla"Including figures
You can include figures from script output as results, or figures from files in your directory. First, let’s see how you can add an image from a file to your markdown.
